
package il.ac.biu.cs.grossmm.api.simple;

/*
 * TODO: Should a throttling mechanism be defined here? (see 4.4.10. of RFC
 * 3265)
 */

import il.ac.biu.cs.grossmm.api.presence.ResourceType;

import javax.sip.address.URI;
import javax.sip.message.Request;
import javax.sip.message.Response;

/**
 * This interface represents an entity implementing SIP-specific event
 * notification package or template package (RFC 3265). Instances implementing
 * this interface should be attached to
 * <code>ISipEventNotificationProvider</code> object to receive subscriptions.
 * 
 * <p>
 * <i> <b>Definition:</b> Event Package: An event package is an additional
 * specification which defines a set of state information to be reported by a
 * notifier to a subscriber. Event packages also define further syntax and
 * semantics based on the framework defined by this document required to convey
 * such state information. </i>
 * 
 * <p>
 * Event packages must/may define the following:
 * <li> MUST define the behavior for SUBSCRIBE requests without "Accept" headers
 * (This header, if present, indicates the body formats allowed in subsequent
 * NOTIFY requests)
 * <li> MAY define parameters for the Event header; if they do so, they must
 * define the semantics for such parameters.
 * 
 * @see SipNotificationProvider
 */
public interface SipEventPackage {

	/**
	 * Returns the name of the package. As specified in RFC 3265 this value
	 * appears in the Event header field present in SUBSCRIBE and NOTIFY
	 * requests within this package.
	 * 
	 * @return package name ( == event type)
	 */
	String getPackageName();

	/**
	 * the MIME types of event bodies expected in NOTIFY requests as array of
	 * pairs (array of arrays of size 2) where the first element in each pair is
	 * the main contain type and the second element is the subtype. The same
	 * value should be returned on each method call.
	 * 
	 * @return the MIME types of event bodies expected in NOTIFY requests as
	 *         array of pairs (array of arrays of size 2) where the first
	 *         element in each pair is the main contain type and the second
	 *         element is the subtype. The same value should be returned on each
	 *         method call.
	 */
	String[][] getMimeTypes();

	/**
	 * Returns true if this is a template package, i.e. allows subscription to
	 * some META-data (e.g. subscription states) of any other event package,
	 * otherwise returns false.
	 * 
	 * @return true iff this is a template package, the same value should be
	 *         returned on each method call
	 */
	boolean isTemplatePackage();

	/**
	 * Returns default subscription expiration time as defined by the package
	 * 
	 * @return default subscription expiration time as defined by the package,
	 *         the same value should be returned on each method call
	 */
	int getDefaultExpiration();

	/**
	 * Returns a minimum subscription expiration time. If a watcher tries to
	 * subscribe with an expiration time greater than zero AND less than this
	 * minimum, "423 Interval too small" error will be sent to it.
	 * <p>
	 * The returned value MUST be less than one hour. To disable the
	 * minimum-expiration-time feature, 0 should be returned.
	 * 
	 * @return minimum subscription expiration time, the same value should be
	 *         returned on each method call
	 */
	int getMinimumExpiration();

	/**
	 * Given an entity uri, a SUBSCRIBE request and <tt>SipSubscription</tt>
	 * object performs internal subscription for the corresponding resource. The
	 * method may returns a sip resopnse if resource cannot be determined due to
	 * some reason (resource does not exist, perse error, etc)
	 * 
	 * @param uri
	 *            the uri of the entity to subscriber (as derived from the
	 *            SUBSCRIBE request)
	 * 
	 * @param subscribeReq
	 *            the subscripton request
	 * 
	 * @param sipSub
	 *            <tt>SipSubscription</tt> object for this subscription
	 * 
	 * @return null on success, othewise SIP response which describes the
	 *         problem
	 * 
	 */
	Response subscribe(URI uri, Request subscribeReq, SipSubscription sipSub);
	
	/**
	 * Given a SUBSCRIBE request which is a subscrition refresh, and 
	 * a <tt>SipSubscription</tt> object performs internal subscription for the corresponding resource. The
	 * method may returns a sip resopnse if resource cannot be determined due to
	 * some reason (resource does not exist, perse error, etc)
	 * 
	 * @param subscribeReq
	 *            the subscripton request
	 * 
	 * @param sipSub
	 *            <tt>SipSubscription</tt> object for this subscription
	 * 
	 * @return null on success, othewise SIP response which describes the
	 *         problem
	 * 
	 */
	Response refresh(Request subscribeReq, SipSubscription sipSub);
	
	/**
     * Given a SIP event-type returns corresponding resource type.
     * If this package is a simple package, then event type should match
     * the name of the package, otherwise it should end with the name
     * of the package. 
     *  
     * @param eventType
     * @return null on success, othewise SIP response which describes the
	 *         problem
     */
	ResourceType getResourceType(String eventType); 
}
